feat(agentcore): add agentcore runtime L2 construct #35623

dineshSajwan · 2025-09-29T22:32:48Z

Issue # (if applicable)

Related to aws/aws-cdk-rfcs#785

Reason for this change

Adding bedrock agent core runtime and runtime endpoint

Description of changes

Added a new L2 construct for runtime in aws -bedrock-agentcore-alpha package.
Added a new L2 construct for runtime endpoint
Added test cases
Added documentation

Describe any new or updated permissions being added

The runtime creates a role with permission to ecr repo, cloudwatch , xray .

Description of how you validated changes

Unit tests, integration tests, manual tests

Checklist

[Yes] My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

aws-cdk-automation

(This review is outdated)

✅ Updated pull request passes all PRLinter validations. Dismissing previous PRLinter review.

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/perms.ts

alvazjor · 2025-10-02T12:36:30Z

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-artifact.ts

+/**
+ * Agent runtime artifact configuration for Bedrock Agent Core Runtime
+ */
+export interface AgentRuntimeArtifactConfig {


Are we expecting this configuration to have more elements in the future? Do you know if there are plans for that? Seems like having this interface at the moment is not adding too much value, you could potentially return the URI directly in the bind method rather than this object (in CDK, we tend to favor flat composition over nested composition if we can)

This mirrors the cloudformation structure of agentruntimeartifact . IMHO, we should keep it as cloud formation structure because if the underlying service add any new field in this object then the flat structure of containeruri may cause breaking changes for the L2 construct.

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime.ts

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/types.ts

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime.ts

alvazjor · 2025-10-02T13:52:48Z

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime.ts

+   * @param clientId Cognito App Client ID
+   * @param region Optional AWS region (defaults to stack region)
+   */
+  public configureCognitoAuth(


This and the other methods below are exactly what I was expecting to see instead of https://github.com/aws/aws-cdk/pull/35623/files#r2398909386.
Simple and specific for each type of auth configuration. I would prefer to keep only this idea and drop the possibility for the user to set up manually the auth config with all the possible wrong combinations they could make if we let it fully configurable.

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-endpoint-base.ts

alvazjor · 2025-10-02T14:07:01Z

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-endpoint.ts

+  public readonly endpointName: string;
+  public readonly agentRuntimeArn: string;
+  public readonly status?: string;
+  public readonly targetVersion?: string;


What is the difference between this and the agentRuntimeVersion ?

We actually have two of those liveVersion and targetVersion. I have added liveVersion with this new commit.

this.liveVersion = this.endpointResource.attrLiveVersion; this.targetVersion = this.endpointResource.attrTargetVersion;

https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-bedrockagentcore-runtimeendpoint.html

https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agent-runtime-versioning.html

As per my understanding

Initial Creation :

You set agentRuntimeVersion: "1"

Both liveVersion and targetVersion will be "1"

Status: READY

During Update :

Update runtime version to "2"

liveVersion remains "1"

targetVersion becomes "2" (transitioning to this)

Status: UPDATING

After Update Completes :

Both liveVersion and targetVersion become "2"

Status: READY

I dont mind having this if CFN also provides it, but I also dont get how this is useful. CDK does not allow interaction "during updates'. In CDK, this will generate a reference to a value that is actually available only after this resource is deployed, and by that time, both liveVersion and targetVersion will be have the same value. Again, I dont mind having it, since CFN is providing it, but lets make the documentation as clear as possible about the differences of both fields

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-endpoint.ts

Pull request has been modified.

alvazjor · 2025-10-08T13:49:25Z

...s/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-authorizer-configuration.ts

+   *
+   * @returns RuntimeAuthorizerConfiguration for IAM authentication
+   */
+  public static configureIAM(): RuntimeAuthorizerConfiguration {


Rename to: usingIAM

alvazjor · 2025-10-08T13:55:02Z

...s/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-authorizer-configuration.ts

+   * @param allowedAudience Optional array of allowed audiences
+   * @returns RuntimeAuthorizerConfiguration for JWT authentication
+   */
+  public static configureJWT(


Rename to usingJWT

alvazjor · 2025-10-08T13:55:20Z

...s/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-authorizer-configuration.ts

+   * @param region Optional AWS region where the User Pool is located (defaults to stack region)
+   * @returns RuntimeAuthorizerConfiguration for Cognito authentication
+   */
+  public static configureCognito(


Rename to usingCognito

alvazjor · 2025-10-08T13:55:49Z

...s/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-authorizer-configuration.ts

+   * @param scopes Optional array of OAuth scopes
+   * @returns RuntimeAuthorizerConfiguration for OAuth authentication
+   */
+  public static configureOAuth(


Rename to usingOAuth

alvazjor · 2025-10-08T13:56:55Z

...s/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-authorizer-configuration.ts

+    provider: string,
+    discoveryUrl: string,
+    clientId: string,
+    scopes?: string[],


provider and scopes parameters are ignored in the constructor if the OAuthAuthorizerConfiguration class. Why do we need them here then?

Apparently OAuthAuthorizerConfiguration and JwtAuthorizerConfiguration are behaving same way under the hood . In my view usingOAuth provides a better user experience (having a dedicated usingOAuth method makes it clear that developers are configuring OAuth providers like GitHub or Google, even though the underlying AWS service treats it the same as JWT authentication). I kept provider and scopes for potential future enhancements where we might add OAuth-specific features or some metadata for observability.
I'm happy to remove these unused parameters to keep the code cleaner. Would you prefer I remove them, or keep them documented as reserved for future use?

Lets remove them for now, since they are not used. If we add features that need then, we can introduce them later. In the future, if more specific configuration is required for each OAuth providers, we can introduce special methods, like usingGoogleOAuth or something like that, and in there we request the additional data. From a user perspective, if the name of the method already gives you the provider, is very clear what is the intention behind it, and with the current approach we can manage to introduce this later when needed

alvazjor · 2025-10-08T16:10:51Z

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-endpoint.ts

+   * Optional description for the agent runtime endpoint
+   * @default - No description
+   */
+  readonly description?: string;


CFN has a pattern for this field, lets add it here too please (JSDoc)

alvazjor · 2025-10-08T16:10:57Z

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-endpoint.ts

+   * A list of key:value pairs of tags to apply to this RuntimeEndpoint resource
+   * @default {} - no tags
+   */
+  readonly tags?: { [key: string]: string };


CFN has a pattern for this field, lets add it here too please (JSDoc)

alvazjor · 2025-10-08T16:12:11Z

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-endpoint.ts

+        value: this.description,
+        fieldName: 'Description',
+        minLength: 1,
+        maxLength: 1200,


In CFN doc, the max length is 256

Ahh they changed it. Will update thanks.

alvazjor · 2025-10-08T16:34:14Z

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime.ts

+    const account = Stack.of(this).account;
+
+    // ECR Image Access - scoped to account repositories
+    role.addToPolicy(new iam.PolicyStatement({


This policy is needed if the runtime artifact is fromEcrRepository right? Could we check if the agentRuntimeArtifact is of type EcrImage to add this policy? And maybe even restrict the resource to that specific one?

I was following these permission as per this . However , I realized that ECR permissions are redundant for L2 construct because these are already handled with AgentRuntimeArtifact bind function with grantPull. The ecr grantPull take care of permissions in best possible way. We need these permission during bind so that it can pull the image from ecr repository before deploying it on runtime. I have removed these permission from createExecutionRole and have tested the changes.

alvazjor · 2025-10-08T16:35:30Z

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime.ts

+    }));
+
+    // ECR Token Access - must be * for authorization token
+    role.addToPolicy(new iam.PolicyStatement({


Same as the previous policy, if only needed when artifact is fromEcrRepository, we should try and restrict the creation only in that case

same as above , removed the permission as they were redundant and using ecr grantPull to grant the permission.

Pull request has been modified.

…ws-cdk into agentcore-runtime

dinsajwa added 4 commits September 29, 2025 11:57

feat(agentcore): added runtime and endpoint

9605217

feat(runtime): added integ test

356c42d

feat(runtime): added integ test

b124520

feat(runtime): updated integ test and readme

cfad025

github-actions bot added p2 repeat-contributor [Pilot] contributed between 3-5 PRs to the CDK labels Sep 29, 2025

aws-cdk-automation requested a review from a team September 29, 2025 22:32

aws-cdk-automation previously requested changes Sep 29, 2025

View reviewed changes

dineshSajwan changed the title ~~feat(agentcore): add agentcore runtime L2 constructs~~ feat(agentcore): add agentcore runtime L2 construct Sep 29, 2025

dineshSajwan and others added 2 commits September 29, 2025 18:43

Merge branch 'aws:main' into agentcore-runtime

a4cd8b7

feat(runtime): adding integ snapshot and documentation

910cf05

alvazjor self-assigned this Sep 30, 2025

dineshSajwan and others added 5 commits September 30, 2025 11:09

Merge branch 'aws:main' into agentcore-runtime

7a306af

feat(runtime): updated doc to fix rosetta build issue

778e5b0

Merge branch 'aws:main' into agentcore-runtime

bae6962

feat(runtime): updated docs for auth and fix issue in runtime

e301efd

feat(runtime): updated docs for auth and fix issue in runtime

150b222

alvazjor previously requested changes Oct 2, 2025

View reviewed changes

feat(runtime): review comments implemented

ea39263

dineshSajwan and others added 3 commits October 6, 2025 13:02

Merge branch 'aws:main' into agentcore-runtime

a4a2ccf

feat(runtime): updated docs

0062054

Merge branch 'main' into agentcore-runtime

d20e5a3

dineshSajwan marked this pull request as ready for review October 6, 2025 19:40

feat(runtime): removed unwanted method

4b87383

dineshSajwan had a problem deploying to deployment-integ-test October 7, 2025 13:54 — with GitHub Actions Error

Merge branch 'main' into agentcore-runtime

8b227b8

dineshSajwan had a problem deploying to deployment-integ-test October 7, 2025 13:55 — with GitHub Actions Error

alvazjor previously requested changes Oct 8, 2025

View reviewed changes

dineshSajwan and others added 2 commits October 9, 2025 13:02

Merge branch 'aws:main' into agentcore-runtime

f48b7bf

feat(runtime): added review comments and fixed integ test

3c058da

dinsajwa and others added 10 commits October 9, 2025 13:50

feat(agentcore): removed unwanted params from oauth

13ffd1d

feat(agentcore): updated runtime

a74054f

feat(agentcore): updated runtime with connection object

7f541d5

Merge branch 'aws:main' into agentcore-runtime

2e18add

Merge branch 'aws:main' into agentcore-runtime

2bd3112

feat(runtime): updated test cases

f724588

feat(agenctcore): added vpcconfig for runtime

bab3f14

Merge branch 'main' into agentcore-runtime

028bbaa

feat(agenctcore): updated test with test account

8f1e9bb

Merge branch 'agentcore-runtime' of https://github.com/dineshSajwan/a…

7a69a05

…ws-cdk into agentcore-runtime

feat(agentcore): add agentcore runtime L2 construct #35623

Are you sure you want to change the base?

feat(agentcore): add agentcore runtime L2 construct #35623

Uh oh!

Conversation

dineshSajwan commented Sep 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Issue # (if applicable)

Reason for this change

Description of changes

Describe any new or updated permissions being added

Description of how you validated changes

Checklist

Uh oh!

aws-cdk-automation left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dineshSajwan Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dineshSajwan Oct 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alvazjor Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

dineshSajwan commented Sep 29, 2025 •

edited

Loading

aws-cdk-automation left a comment •

edited

Loading

dineshSajwan Oct 3, 2025 •

edited

Loading

dineshSajwan Oct 8, 2025 •

edited

Loading

alvazjor Oct 9, 2025 •

edited

Loading